home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / Pod / Simple / LinkSection.pm < prev    next >
Encoding:
Text File  |  2009-06-26  |  3.5 KB  |  146 lines
  1.  
  2. require 5;
  3. package Pod::Simple::LinkSection;
  4.   # Based somewhat dimly on Array::Autojoin
  5.  
  6. use strict;
  7. use Pod::Simple::BlackBox;
  8.  
  9. use overload( # So it'll stringify nice
  10.   '""'   => \&Pod::Simple::BlackBox::stringify_lol,
  11.   'bool' => \&Pod::Simple::BlackBox::stringify_lol,
  12.   # '.='   => \&tack_on,  # grudgingly support
  13.   
  14.   'fallback' => 1,         # turn on cleverness
  15. );
  16.  
  17. sub tack_on {
  18.   $_[0] = ['', {}, "$_[0]" ];
  19.   return $_[0][2] .= $_[1];
  20. }
  21.  
  22. sub as_string {
  23.   goto &Pod::Simple::BlackBox::stringify_lol;
  24. }
  25. sub stringify {
  26.   goto &Pod::Simple::BlackBox::stringify_lol;
  27. }
  28.  
  29. sub new {
  30.   my $class = shift;
  31.   $class = ref($class) || $class;
  32.   my $new;
  33.   if(@_ == 1) {
  34.     if (!ref($_[0] || '')) { # most common case: one bare string
  35.       return bless ['', {}, $_[0] ], $class;
  36.     } elsif( ref($_[0] || '') eq 'ARRAY') {
  37.       $new = [ @{ $_[0] } ];
  38.     } else {
  39.       Carp::croak( "$class new() doesn't know to clone $new" );
  40.     }
  41.   } else { # misc stuff
  42.     $new = [ '', {}, @_ ];
  43.   }
  44.  
  45.   # By now it's a treelet:  [ 'foo', {}, ... ]
  46.   foreach my $x (@$new) {
  47.     if(ref($x || '') eq 'ARRAY') {
  48.       $x = $class->new($x); # recurse
  49.     } elsif(ref($x || '') eq 'HASH') {
  50.       $x = { %$x };
  51.     }
  52.      # otherwise leave it.
  53.   }
  54.  
  55.   return bless $new, $class;
  56. }
  57.  
  58. # Not much in this class is likely to be link-section specific --
  59. # but it just so happens that link-sections are about the only treelets
  60. # that are exposed to the user.
  61.  
  62. 1;
  63.  
  64. __END__
  65.  
  66. # TODO: let it be an option whether a given subclass even wants little treelets?
  67.  
  68.  
  69. __END__
  70.  
  71. =head1 NAME
  72.  
  73. Pod::Simple::LinkSection -- represent "section" attributes of L codes
  74.  
  75. =head1 SYNOPSIS
  76.  
  77.  # a long story
  78.  
  79. =head1 DESCRIPTION
  80.  
  81. This class is not of interest to general users.
  82.  
  83. Pod::Simple uses this class for representing the value of the
  84. "section" attribute of "L" start-element events.  Most applications
  85. can just use the normal stringification of objects of this class;
  86. they stringify to just the text content of the section,
  87. such as "foo" for
  88. C<< LZ<><Stuff/foo> >>, and "bar" for 
  89. C<< LZ<><Stuff/bIZ<><ar>> >>.
  90.  
  91. However, anyone particularly interested in getting the full value of
  92. the treelet, can just traverse the content of the treeleet
  93. @$treelet_object.  To wit:
  94.  
  95.  
  96.   % perl -MData::Dumper -e
  97.     "use base qw(Pod::Simple::Methody);
  98.      sub start_L { print Dumper($_[1]{'section'} ) }
  99.      __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>')
  100.     "
  101. Output:
  102.   $VAR1 = bless( [
  103.                    '',
  104.                    {},
  105.                    'b',
  106.                    bless( [
  107.                             'I',
  108.                             {},
  109.                             'ar'
  110.                           ], 'Pod::Simple::LinkSection' ),
  111.                    'baz'
  112.                  ], 'Pod::Simple::LinkSection' );
  113.   
  114. But stringify it and you get just the text content:
  115.  
  116.   % perl -MData::Dumper -e
  117.     "use base qw(Pod::Simple::Methody);
  118.      sub start_L { print Dumper( '' . $_[1]{'section'} ) }
  119.      __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>')
  120.     "
  121. Output:
  122.   $VAR1 = 'barbaz';
  123.  
  124.  
  125. =head1 SEE ALSO
  126.  
  127. L<Pod::Simple>
  128.  
  129. =head1 COPYRIGHT AND DISCLAIMERS
  130.  
  131. Copyright (c) 2002 Sean M. Burke.  All rights reserved.
  132.  
  133. This library is free software; you can redistribute it and/or modify it
  134. under the same terms as Perl itself.
  135.  
  136. This program is distributed in the hope that it will be useful, but
  137. without any warranty; without even the implied warranty of
  138. merchantability or fitness for a particular purpose.
  139.  
  140. =head1 AUTHOR
  141.  
  142. Sean M. Burke C<sburke@cpan.org>
  143.  
  144. =cut
  145.  
  146.